/*
 * 2005-11-19 lxm 创建。 
 */
package com.hd123.rumba.organization;

import java.util.List;

import net.sf.hibernate.HibernateException;

import com.hd123.rumba.exception.BusinessException;
import com.hd123.rumba.runtime.IManager;
import com.hd123.rumba.runtime.OperateContext;
import com.hd123.rumba.sql.ResultPage;
import com.hd123.rumba.user.IUser;
import com.hd123.rumba.util.ClassifiedHashtable;

/**
 * @author lxm
 * 
 * 组织，管理员，接口
 * 
 */
public interface IOrganizationMgr extends IManager {

  /**
   * 创建一个空的组织对象。
   * <p>
   * 提供给Web Service数据交换。
   * 
   * @return
   * @throws BusinessException
   * @throws HibernateException
   */
  public IOrganization createOrganization() throws BusinessException;

  /**
   * 新建一个组织
   * 
   * @param upperOrg
   *          上级组织。允许空，表示创建顶级组织。
   * @param code
   *          组织代码
   * @return
   * @throws BusinessException
   * @throws HibernateException
   */
  public IOrganization createOrganization(IOrganization upperOrg, String code)
      throws BusinessException, HibernateException;

  /**
   * 向指定组织添加组织角色。
   * <p>
   * 
   * 有可能被添加的组织角色已经被包含在指定组织中，则不作任何事；若已经存在相同类型的组织角色，且<br>
   * 并不是同一个对象，将产生DuplicateIdException。
   * 
   * @param organization
   *          被修改的组织。
   * @param role
   *          被添加的组织角色。
   * @throws BusinessException
   * @throws HibernateException
   */
  public void addRoleToOrganization(IOrganization organization, IOrgRole role)
      throws BusinessException, HibernateException;

  /**
   * 从指定的组织中物理删除角色
   * <p>
   * 
   * @param organization
   *          被修改的组织。
   * @param role
   *          被删除的组织角色。
   * @throws BusinessException
   * @throws HibernateException
   */
  public void removeRoleFromOrganization(IOrganization organization, IOrgRole role)
      throws BusinessException, HibernateException;

  /**
   * 检查指定组织的合法性
   * 
   * @param organization
   *          被检查的组织。
   * @param withWarn
   * @return
   * @throws BusinessException
   * @throws HibernateException
   */
  public ClassifiedHashtable verifyOrganization(IOrganization organization, boolean withWarn)
      throws BusinessException, HibernateException;

  /**
   * 保存指定的组织
   * <p>
   * 
   * 同时保存组织所有的组织角色。将按照规则同步修改对应组织域的信息，包括域的状态。
   * 
   * @param organization
   *          被保存的组织
   * @param toState
   *          目标状态，取值：VALUE_STATE_USING | VALUE_STATE_DELETED。<br>
   *          注意：业务上禁止直接通过IOrganization.setState()改变其状态。
   * @param operator
   * @param oca
   * @throws BusinessException
   * @throws HibernateException
   * @deprecated
   */
  public void saveOrganization(IOrganization organization, Integer toState, IUser operator, long oca)
      throws BusinessException, HibernateException;

  /**
   * 保存指定的组织
   * <p>
   * 
   * 同时保存组织所有的组织角色。将按照规则同步修改对应组织域的信息，包括域的状态。
   * 
   * @param organization
   *          被保存的组织
   * @param operator
   * @throws BusinessException
   * @throws HibernateException
   * @deprecated
   */
  public void saveOrganization(IOrganization organization, IUser operator)
      throws BusinessException, HibernateException;

  /**
   * 保存指定的组织
   * <p>
   * 
   * 同时保存组织所有的组织角色。将按照规则同步修改对应组织域的信息，包括域的状态。
   * 
   * @param organization
   *          被保存的组织
   * @param operate
   * @throws BusinessException
   * @throws HibernateException
   */
  public void saveOrganization(IOrganization organization, OperateContext operate)
      throws BusinessException, HibernateException;

  /**
   * （标记）删除指定的组织。
   * 
   * @param organization
   *          指定被删除的组织。
   * @param operator
   * @throws BusinessException
   * @throws HibernateException
   * @deprecated
   */
  public void deleteOrganization(IOrganization organization, IUser operator)
      throws BusinessException, HibernateException;

  /**
   * （标记）删除指定的组织。
   * 
   * @param organization
   *          指定被删除的组织。
   * @param operate
   * @throws BusinessException
   * @throws HibernateException
   */
  public void deleteOrganization(IOrganization organization, OperateContext operate)
      throws BusinessException, HibernateException;

  /**
   * 恢复删除指定的组织。
   * 
   * @param organization
   *          指定被恢复删除的组织。
   * @param operator
   * @throws BusinessException
   * @throws HibernateException
   * @deprecated
   */
  public void undeleteOrganization(IOrganization organization, IUser operator)
      throws BusinessException, HibernateException;

  /**
   * 恢复删除指定的组织。
   * 
   * @param organization
   *          指定被恢复删除的组织。
   * @param operate
   * @throws BusinessException
   * @throws HibernateException
   */
  public void undeleteOrganization(IOrganization organization, OperateContext operate)
      throws BusinessException, HibernateException;

  /**
   * 物理删除指定组织。
   * 
   * @param organization
   *          被删除的组织
   * @throws BusinessException
   * @throws HibernateException
   */
  public void removeOrganization(IOrganization organization) throws BusinessException,
      HibernateException;

  /**
   * 注册一个组织角色（管理员）。
   * 
   * @param roleMgrIntf
   *          被注册的组织角色管理员接口类。
   * @throws BusinessException
   */
  public void registerOrgRoleMgr(Class roleMgrIntf) throws BusinessException;

  /**
   * 清除组织角色（管理员）注册表。
   * 
   */
  public void clearOrgRoleMgrRegistry();

  /**
   * 根据组织角色管理员接口类名取得组织角色管理员实例。
   * 
   * @param intfMgrName
   *          组织角色管理员接口类名。
   * @return 组织角色管理员实例。若未找到返回null。
   * @throws BusinessException
   */
  public IOrgRoleMgr lookupOrgRoleMgr(String intfMgrName);

  /**
   * 根据指定的组织角色，取得对应的组织角色管理员。
   * 
   * @param orgRole
   *          指定的组织角色。
   * @return 组织角色管理员实例。若未找到返回null。
   * @throws BusinessException
   */
  public IOrgRoleMgr lookupOrgRoleMgr(IOrgRole orgRole) throws BusinessException;

  /**
   * 取得所有可用的组织角色列表。<br>
   * 
   * 取得当前所有已经注册的组织角色管理员接口列表。
   * 
   * @return List of IOrgRoleMgr
   * @throws BusinessException
   */
  public List getValidOrgRoleMgrList() throws BusinessException;

  /**
   * 根据uuid取得组织。
   * <p>
   * 
   * 搜索范围包括所有状态的组织。
   * 
   * @param uuid
   * @return
   * @throws BusinessException
   * @throws HibernateException
   */
  public IOrganization getOrganization(String uuid) throws BusinessException, HibernateException;

  /**
   * 根据代码取得组织。
   * <p>
   * 
   * 只在state!=VALUE_STATE_DELETED范围内搜索。
   * 
   * @param code
   *          组织代码。
   * @return
   * @throws BusinessException
   * @throws HibernateException
   */
  public IOrganization getOrganizationByCode(String code) throws BusinessException,
      HibernateException;

  /**
   * 根据代码取得组织。
   * 
   * @param code
   *          组织代码。
   * @param states
   *          符合条件的状态数组。当传入null的时候，表示不约束状态条件，即等价于传入全部的状态。
   * @return
   * @throws BusinessException
   * @throws HibernateException
   */
  public IOrganization getOrganizationByCode(String code, Integer[] states)
      throws BusinessException, HibernateException;

  /**
   * 根据组织域查找组织。
   * <p>
   * 
   * 搜索范围包括所有状态的组织。
   * 
   * @param orgDomainUuid
   *          指定的组织域uuid。
   * @return
   * @throws BusinessException
   * @throws HibernateException
   */
  public IOrganization getOrganizationByOrgDomain(String orgDomainUuid) throws BusinessException,
      HibernateException;

  /**
   * 取得所有的顶级组织。
   * <p>
   * 只在state!=VALUE_STATE_DELETED范围内搜索。
   * 
   * @param pageSize
   * @param page
   * @return
   * @throws BusinessException
   * @throws HibernateException
   */
  public ResultPage getTopOrganizations(int pageSize, int page) throws BusinessException,
      HibernateException;

  /**
   * 取得指定组织的直接所属子组织。
   * <p>
   * 只在state!=VALUE_STATE_DELETED范围内搜索。
   * 
   * @param parentOrg
   *          指定的上级组织
   * @param pageSize
   * @param page
   * @return
   * @throws BusinessException
   * @throws HibernateException
   */
  public ResultPage getLowerOrganizations(IOrganization parentOrg, int pageSize, int page)
      throws BusinessException, HibernateException;

  /**
   * 取得指定组织的直接下级组织。
   * <p>
   * 
   * 只在state!=VALUE_STATE_DELETED范围内搜索。
   * 
   * @param parentOrg
   *          指定的上级组织
   * @return
   * @throws BusinessException
   * @throws HibernateException
   */
  public List getLowerOrganizations(IOrganization parentOrg) throws BusinessException,
      HibernateException;

  /**
   * 取得指定组织的所有子孙组织（不包括已删除的组织）。
   * 
   * @param parentOrg
   *          所属上级组织
   * @return 子孙组织列表，如果所属上级组织为null，则返回所有组织。
   * @throws BusinessException
   * @throws HibernateException
   */
  public List<IOrganization> getAllLowerOrganizations(IOrganization parentOrg)
      throws BusinessException, HibernateException;

  /**
   * 取得指定组织的所属顶级组织。
   * 
   * @param org
   *          指定的组织。
   * @return 所属顶级组织。
   * @throws BusinessException
   * @throws HibernateException
   */
  public IOrganization getTopOrganization(IOrganization org) throws BusinessException,
      HibernateException;
}
